The Castor mapping file also provides a mechanism for binding a Java object model to a relational database model. This is usually referred to as object-to-relational mapping (O/R mapping). O/R mapping bridges the gap between an object model and a relational model.

The mapping file provides a description of the Java object model to Castor JDO. Via Castor XML, Castor JDO uses the information in the mapping file to map Java objects to relational database tables. The following is a high-level example of a mapping file:

      <mapping>
          <class>
              <map-to />
              <field>
                  <sql />
              </field>
              ...
          </class>
      </mapping>
      

Each Java object is represented by a <class> element composed of attributes, a <map-to> element and <field> elements. The <map-to> element contains a reference to the relational table to which the Java object maps. Each <field> element represents either a public class variable or a the variable's accessor/mutator methods (depending upon the mapping info). Each <field> element is composed of attributes and one <sql> element. The <sql> element represents the field in the relational table to which the <field> element maps.

It is possible to use the mapping file and Castor's default behavior in conjunction. When Castor handles an object but is unable to locate information about it in the mapping file, it will rely upon its default behavior. Castor makes use of the Java programming language Reflection API to introspect the Java objects to determine the methods to use. This is the reason some attributes are not required in the mapping file.

        <!ELEMENT class ( description?, cache-type?, map-to?, field+ )>
        <!ATTLIST class
                  name            ID       #REQUIRED
                  extends         IDREF    #IMPLIED
                  depends         IDREF    #IMPLIED
                  auto-complete   ( true |false ) "false"
                  identity        CDATA    #IMPLIED
                  access          ( read-only | shared | exclusive | db-locked )  "shared"
                  key-generator   IDREF    #IMPLIED >
        

The <class> element contains all the information used to map a Java object to a relational database. The content of <class> is mainly used to describe the fields that will be mapped.

Description of the attributes:

Description of the elements:

        <!ELEMENT map-to EMPTY>
        <!ATTLIST map-to
                  table      NMTOKEN  #IMPLIED
                  xml        NMTOKEN  #IMPLIED
                  ns-uri     NMTOKEN  #IMPLIED
                  ns-prefix  NMTOKEN  #IMPLIED
                  ldap-dn    NMTOKEN  #IMPLIED
                  ldap-oc    NMTOKEN  #IMPLIED>
        

<map-to> is used to specify the name of the item that should be associated with the given Java object. The <map-to> element is only used for the root Java object.

Description of the attributes:

        <!ELEMENT field ( description?, sql?, xml?, ldap? )>
        <!ATTLIST field
                  name           NMTOKEN  #REQUIRED
                  type           NMTOKEN  #IMPLIED
                  required       ( true | false )  "false"
                  direct         ( true | false )  "false"
                  lazy           ( true | false )  "false"
                  transient      ( true | false )  "false"
                  get-method     NMTOKEN  #IMPLIED
                  set-method     NMTOKEN  #IMPLIED
                  create-method  NMTOKEN  #IMPLIED
                  collection     ( array | vector | hashtable | collection | set | map )  #IMPLIED>
        

The <field> element is used to describe a property of a Java object. It provides:

From this information, Castor is able to access a given property in the Java object.

In order to determine the signature that Castor expects, there are two easy rules to apply.

1. Determine <type>.

It is necessary to use a collection when the content model of the element expects more than one element of the specified type. This is how the 'to-many' portion of a relationship is described.

2. Determine the signature of the method

        public <type> <name>;
        

        public <type> <get-method>();
        

        public void <set-method>(<type> value);
        

        public <type> get<capitalized-name>();
        

        public void set<capitalized-name>(<type> value);
        

          <!ELEMENT sql EMPTY>
          <!ATTLIST sql
              name        NMTOKENS  #IMPLIED
              type        NMTOKENS  #IMPLIED
              many-key    NMTOKENS  #IMPLIED
              many-table  NMTOKEN   #IMPLIED
              read-only   ( true | false )    "false"
              dirty       ( check | ignore )  "check">
  
          

package myapp;

public class Product 
{
    private int       _id;

    private String    _name; 

    private float     _price; 

    private ProductGroup _group;


    public int getId()
    ...

    public void setId( int anId )
    ...

    public String getName()
    ...

    public void setName( String aName )
    ...

    public float getPrice()
    ...

    public void setPrice( float aPrice )
    ...

    public ProductGroup getProductGroup()
    ...

    public void setProductGroup( ProductGroup aProductGroup )
    ...
}
                    

create table prod 
(
  id        int           not null,
  name      varchar(200)  not null,
  price     numeric(18,2) not null,
  group_id  int           not null
);
                    

<?xml version="1.0"?>
<!DOCTYPE mapping PUBLIC "-//EXOLAB/Castor Object Mapping DTD Version 1.0//EN"
                         "http://castor.exolab.org/mapping.dtd">
<mapping>

    <class name="myapp.Product" identity="id">

        <map-to table="prod" />

        <field name="id" type="integer">
            <sql name="id" type="integer" />
        </field>

        <field name="name" type="string">
            <sql name="name" type="char" />
        </field>

        <field name="price" type="float">
            <sql name="price" type="numeric" />
        </field>

        <field name="group" type="myapp.ProductGroup" >
            <sql name="group_id" />
        </field>

    </class>

</mapping>